home *** CD-ROM | disk | FTP | other *** search
Text File | 1998-08-09 | 39.3 KB | 740 lines | [ TEXT/CWIE]
//WSAPI.h /* WebSTAR API Interface, v1.1 Copyright ©1996, StarNine Techologies, Inc. All rights reserved. This file defines the public interface between the WebSTAR plug-in framework and user-defined plug-in routines. */ #ifndef WSAPI_Included #define WSAPI_Included 1 #if GENERATINGPOWERPC #pragma options align=mac68k #endif #ifdef __cplusplus extern "C" { #endif #define WSAPI_VERSION (unsigned long) 0x01010000 //Do NOT modify this value #define WSAPI_MAC 1 #include <AppleEvents.h> extern unsigned long wsapi_lib_version; // the version of the WSAPI library code this plug-in is linked with. Useful // for making sure your plug-in was built with libs that match the interfaces, etc. // enums that identify what type of server is "glued" to the WSAPI plug-in. Useful for determining the callback // and parameter feature set that will be available at run-time. See wsapi_glue_type variable below. typedef enum { WSAPI_Mac_Glue, //plug-in is built as a WebSTAR Mac plug-in WSAPI_PC_Glue, //plug-in is built as a WebSTAR 95 or NT plug-in NSAPI_Glue, //plug-in is built as a Netscape plug-in ISAPI_Glue //plug-in is built as a Microsoft plug-in } WSAPI_Server_Glue_Type; extern WSAPI_Server_Glue_Type wsapi_glue_type; //what type of glue libraries are being used by the plug-in? #define WSAPI_NAME_SIZE 32 #define WSAPI_FILE_NAME_SIZE 256 /*size of text representations of file paths*/ #define WSAPI_VERSION_STR_SIZE 12 /*size of the version string returned in the init message pb*/ #define WSAPI_INDEX_SIZE 64 //the maximum length of index selectors used with Get and SetIndexedParameter #define WSAPI_IPC_CONNECTION_MASK 0x00003FFF //See WSAPI_SendIPCMessage below // Not completely implemented yet. You may set these flags, but WebSTAR ignores them for now. // Flags that define capabilities that the plug-in can perform or services it wants to take advantage of // Used in the "capabilities" field of the Init message's PB record. Your plug-in should OR the appropriate // flags together and assign them to the capabilities field which is returned to the server at the completion of the // Init message handling. The server will use these flags to determine if a user has misconfigured your plug-in for // a role that it cannot support. #define capISAPISubset (unsigned long) 0x00000001 //restrict plug-in to ISAPI compatible calls - not implemented yet #define capCGI (unsigned long) 0x00000002 //plug-in is willing to operate as a normal CGI plug-in #define capPreProcessor (unsigned long) 0x00000004 //p.i. will work as a preprocessor #define capPostProcessor (unsigned long) 0x00000008 //p.i. will work as a postprocessor #define capLogging (unsigned long) 0x00000010 //p.i. will receive logging and status messages - not implemented yet #define capSecurity (unsigned long) 0x00000020 //p.i. will perform security checks - not implemented yet #define capNSAPISubset (unsigned long) 0x00000040 //restrict plug-in to NSAPI compatible calls - not implemented yet /*****************************************************************************/ /*## Important note to developers: Not all servers will implement all of these parameters. It is up to individual server implementors to decide which parameters will be supported, since some of these are WebSTAR-specific. It is possible that other server implementors will add additional parameters beyond the ones supported by WebSTAR as well. */ /** Keywords used to get/set WebSTAR parameters with WSAPI_Get/SetParameter **/ /** Note that these have the same definitions and formats as AppleEvent parameters of the same value. With the exceptions noted below, all parameters are of type "typeChar." The two numeric values below should be noted. **/ typedef enum { piPathArgKeyword = '----', piSearchArgKeyword = 'kfor', piUserKeyword = 'user', piPasswordKeyword = 'pass', piFromUser = 'frmu', piAddressKeyword = 'addr', piPostKeyword = 'post', piMethodKeyword = 'meth', piServerName = 'svnm', piServerPort = 'svpt', //typeShortInteger - IP port (e.g, 80) piScriptName = 'scnm', piContentType = 'ctyp', piContentLength = 'CLen', //typeLongInteger - the content-length header field (if any) from HTTP request piRefererKeyword = 'refr', piUserAgentKeyword = 'Agnt', piActionKeyword = 'Kact', piActionPathKeyword = 'Kapt', piClientIPAddress = 'Kcip', //typeLongInteger - 4 byte IP address piFullRequestKeyword = 'Kfrq', //new for plug-ins only piFileMIMEType = 'Mime', // The MIME type of the URL in piScriptName piServerField = 'SvFd', // The HTTP header field for this server. e.g., "Server: WebSTAR/1.3 ID/22" piServerDirectoryPath = 'SPth', // A C string representing the complete (machine-specific) path name of the server's working directory piURLPhysicalPath = 'UPth', // If the URL represents an actual file in the file system, this parameter contains its name relative to the server's root. piIfModifiedSince = 'IfMS', // short. True if the file has been modified since last retrieval or if modification cannot be determined. False if unchanged. piIfModifiedDate = 'IfMD', //## typeChar, R/O, if-modified-since date string from HTTP request header piCurrentRealm = 'CRlm', // typeChar, 256 max. The realm (if any) that the requested URL belongs to. // WSAPI_E_RequestFailed will be returned by GetParameter if this value isn't defined for the current request. piURLFileRef = 'Pufr', //## typeFSS, R/0, Server-specific reference to file in the native O/S. On the // Mac with WebSTAR, this is a FSSpec to actual file being requested if it // really exists on disk. Nonexistent files will have a FSSpec that has all // fields set to zero and the name field will be empty. //****************************** //log- and status-related values piConnectionID = 'LCID', //long - unique # for each connection for this run of the server piServerUniqueID = 'LSID', //long - unique # across all current server invocations on this machine // note: the value of the WebSTAR message-id: field can be generated with the following C printf format, // using the values of the preceding two properties: // printf ("<%0lx.%ld@%s>", serverUniqueIDVar, connectionIDVar, hostnameVar); //***************************** // The following parameters are read-only and represent information present in the server's // status display and/or the information broadcast to remote logging processes. piTotalConnections = 'STCn', // long. Total connections the server has received since it started up piCurrentUserLevel = 'SCLd', // short. Current number of users connected to the server at this time piHighestUserLevel = 'SMLd', // short. Max number of users ever connected to the server at once piCurrentFreeMemory = 'SFMm', // long. Amount of free memory available to the server process piMinimumFreeMemory = 'SMFM', // long. Minimum amount of free memory that was ever available to the server process piTotalConTimeouts = 'STTm', // short. Total number of client connections that timed out before completion piTotalConBusies = 'STBz', // short. Total number of client connections refused because the server was too busy piTotalConDenied = 'STDn', // short. Total number of client connections denied by domain name or IP address piTotalBytesSent = 'TByt', // long. Total number of bytes sent by the server piUpSinceDate = 'SUpS', // C string. Date & time the server was launched; Format, MM/DD/YY:HH:MM piPluginAdminInfo = 'Padm', //##typeChar, R/O, text block containing info on each plug-in currently installed // tab separated syntax of each line is: <name> <version> <Admin URL path><cr> //****************************** // ##These four parameters describe the plug-in environment, including the physical location of plug-ins // and information about each parameter that can be manipulated at runtime to determine range checks, types, // string representations, etc. See the W*API docs for details on the format of the piPluginParamInfo data structure. piPluginParamInfo = 'Pipi', //##typeLong, R/O, pointer to a W*API-specific data structure describing plug-in parameter semantics piPluginParamCount = 'Pipc', //##typeSMInt, R/O, count of the number of W*API parameters in piPluginParamInfo piPluginDirPath = 'Pdph', //##typeChar, R/O, full path to the plug-ins folder piPluginDirFSSpec = 'Pdfs', //##typeFSS, R/O, platform-specific file system reference to plug-ins folder //****************************** //the following 3 values are only guaranteed to be set AFTER a connection has been completed // and logged. (i.e., only access them from a post-processor plug-in.) piTransferResult = 'LTRs', //OK, PRIV, or ERR! string, depending on transfer result piBytesSent = 'LByt', //number of bytes written to the HTTP client piTransferTime = 'LTrT', //number of ticks it took from connection open to close //****************************** // WebSTAR properties below here. // These match the definitions in the WebSTAR AETE resource. // The following values are all global WebSTAR properties. piDumpBufSize = 'Dbuf', //typeLongInteger piPigDelay = 'PigD', //typeSMInt piMaxUsers = 'MaxU', //typeSMInt piNoDNS = 'Ndns', //typeSMInt piTimeOut = 'TimO', //typeSMInt piMaxListens = 'MaxL', //typeSMInt piLogging = 'Plog', //typeSMInt piVerboseMessages = 'Pvrb', //typeSMInt piRefuseConnections = 'Pcon', //typeSMInt piHideWindow = 'Phid', //typeSMInt piDefaultMIMEType = 'Pmim', //typeChar piPort = 'Pprt', //typeSMInt piIndexFile = 'Pixf', //typeChar piErrorFile = 'Perf', //typeChar piLogFile = 'Plgf', //typeChar piNoAccessFile = 'Pnaf', //typeChar piSuffixMappings = 'Psuf', //typeChar piAllowDeny = 'Pa/d', //typeChar piAllowDenyByRealm = 'PADr', //##typeChar - R/W, NOTE!! This is an indexed value and you must use the // WSAPI_GetIndexedParameter or WSAPI_SetIndexedParameter call to manipulate it. The Index is // the name of the realm to get or set allow/deny info for. piRealms = 'Prlm', //typeChar piActions = 'Pact', //typeChar piLogFormat = 'Plfm', //typeChar piPreProcessor = 'Ppre', //typeChar piPostProcessor = 'Ppst', //typeChar piVersionNumber = 'Pvrs', //typeChar piReportDelay = 'Prdl', //##typeSMInt - R/W, amount of time in seconds between status report events piCacheFlush = 'Pcfl', //##typeSMInt - W/O, setting this flag indicates the server should flush any // cached data. A plug-in receiving this parameter to a WSAPI_ServerStateChanged // message should interpret it as a signal for the plug-in to flush any cached data // it retains from the local file system. piFileInfoCacheSize = 'Pfic', //##typeLong - R/W, amount of memory to allocate to file info caching piKeepAliveConnections = 'Pkac', //##typeSMInt- R/W, number of connections per client to keep alive piKeepAliveTime = 'Pkat', //##typeSMInt- R/W, seconds to keep alive idle client connections piServerCName = 'Pscn', //##typeChar - R/W, canonical name of server to be used in HTTP responses, regardless of DNS name piCGIBinOnly = 'Pcbo', //##typeSMInt - R/W, flag determining if CGIs will be executed from the /cgi-bin folder only piServiceAddress = 'Pisa' //##typeLong - R/W, INDEXED VALUE, table of registered service addresses // This is a complicated parameter. You should refer to the W*API documentation for details. // The index is the name of the service whose address you wish to register or retrieve. } WSAPI_ParamKeywords; /*****************************************************/ // Parameter block information typedef unsigned long WSAPI_Stream, *WSAPI_StreamPtr; //type for IP callbacks in network stuff below //messages sent to plug-in dispatcher typedef enum { WSAPI_Init, WSAPI_Shutdown, WSAPI_Idle, WSAPI_Run, WSAPI_Emergency, WSAPI_ServerStateChanged, WSAPI_Register, WSAPI_AccessControl, //## WSAPI_Filter //## } WSAPI_Command; //sub-messages sent to plug-in dispatcher in the "role" field when message is "WSAPI_Run" typedef enum { WSAPI_CGI_Role, //running as a normal CGI replacement WSAPI_PreProcessor_Role, //acting as a pre-processor WSAPI_PostProcessor_Role, //acting as a post-processor WSAPI_Logging_Role, //receiving log info WSAPI_Security_Role, //performing an access authorization WSAPI_Error_Role, //handling bad URL requests WSAPI_NoAccess_Role, //handling requests denied by IP or domain WSAPI_Index_Role //handing a request for the default file } WSAPI_Run_Role; //descriptor type used to extract various named parameters available to plug_ins typedef void *WSAPI_DescPtr; /** structure types making up the CommandPB parameter block **/ typedef struct { // now used by both init and register messages short resRef; //in - reference number of plug-in's resource file char pluginName [WSAPI_NAME_SIZE]; //##in/out - the unique name that identifies this plug-in. Initialized to file name. unsigned long capabilities; // out - flags that indicate functions the plug-in can perform or services it wants //## these fields should be filled in during the Register message char version [WSAPI_VERSION_STR_SIZE]; //##out - string representation of the plug-in's version, e.g., "1.0b1" char adminURL [WSAPI_FILE_NAME_SIZE]; //##out - path portion ONLY of URL to configure plug-in, e.g. "/admin.plugsuffix" } WSAPI_InitPB; typedef struct { short unused; //not sure what args shutdown needs to send in and out yet } WSAPI_ShutdownPB; typedef struct { unsigned long ticksToSleep; //out - how long to sleep before WebSTAR's idle handler calls again } WSAPI_IdlePB; typedef struct { WSAPI_Run_Role role; //what is this invocation supposed to do? be a CGI, preprocessor, etc? } WSAPI_RunPB; typedef struct { short unused; } WSAPI_EmergencyPB; typedef struct { WSAPI_ParamKeywords whichParam; // contains the WSAPI_ParamKeywords (parameter) value that has changed } WSAPI_StateChangedPB; typedef struct { short grantAccess; //## boolean flag. If true, the server will process the URL as normal short authRequired; //## boolean flag. If true, the server will require password access } WSAPI_AccessControlPB; typedef struct { //## server sends this structure with the WSAPI_Filter message char *request; //## request contains a pointer to the read-only HTTP request data (not including object body) short requestLength; //## length in characters of the request. Data beyond length bytes should not be modified! char *newRequest; //## null initially. setting pointer to new request data (allocated by you with WSAPI_AllocateMemory ONLY!) //## forces server to replace original request with data you generate for the request instead short newRequestLength; //## zero initially. length in characters of the new request you create. } WSAPI_FilterPB; typedef union { WSAPI_InitPB init; // used by both register and init messages WSAPI_ShutdownPB shutdown; WSAPI_IdlePB idle; WSAPI_RunPB run; WSAPI_EmergencyPB emergency; WSAPI_StateChangedPB stateChanged; // see above WSAPI_AccessControlPB accessControl; //## WSAPI_FilterPB filter; //## } WSAPI_PB_Union; typedef struct { long api_version; //in - what version of API does the server support? void *api_data; //in - private data. DON'T TOUCH! WSAPI_Command command; //in - what operation is the plug-in to perform? WSAPI_PB_Union param; } WSAPI_CommandPB, *WSAPI_CommandPBPtr; // record for holding pending IPC stuff #if WSAPI_MAC typedef struct { AppleEvent theAppleEvent; AppleEvent reply; long handlerRefcon; } WSAPI_IPC_Result, *WSAPI_IPC_ResultPtr; #else typedef struct { void *theIPCMsg; } WSAPI_IPC_Result, *WSAPI_IPC_ResultPtr; #endif //******************************* //##Definitions for the piPluginParamInfo data structure #define WSAPI_PARAM_SIZE 32 typedef struct piparam_table_struct { WSAPI_ParamKeywords param; //one of the enums from above char name[WSAPI_PARAM_SIZE]; //case-sensitive string representation of the parameter's name char index[WSAPI_PARAM_SIZE]; //"name" of the index field. usually maps to a HTML form field name OSType type; //4 character (long) parameter type short mode; //bit field describing read/write access. masks: read = 2, write = 1 long lower; //lower bound for range checking integer parameters long upper; //upper bound for range checking. If less than lower bound, no range is specified void *extra_info; //reserved for future expansion } WSAPI_ParamInfo, *WSAPI_ParamInfoPtr; //******************************* /** Error codes returned by various WSAPI calls **/ typedef enum { WSAPI_I_NoErr, //normal completion code, synonymous with noErr WSAPI_E_MessageNotHandled, //return value indicates the command message wasn't processed WSAPI_E_ParameterNotFound, //requested parameter descriptor did not exist WSAPI_E_InsufficientMemory, //not enough memory to perform requested operation WSAPI_E_Unimplemented, //requested function is not yet implemented or isn't available for this version of WSAPI WSAPI_E_HTTPConnectionGone, //the client connected to this thread has closed the connection WSAPI_E_BadCommandPtr, //commandPtr that was passed was null or invalid WSAPI_E_CantOpenStream, //TCP/IP stream couldn't be created or opened WSAPI_E_BufferTooBig, //data buffer was too large for the callback to process WSAPI_E_NameLookupFailed, //the domain name resolver failed to resolve the requested name WSAPI_E_NullDescriptor, //10, a null descriptor, or one with no data pointer was passed when real data was required WSAPI_E_UnspecifiedError, //some unknown error happened WSAPI_E_BadArgument, //one of the arguments (usually a pointer) passed to a callback was invalid WSAPI_E_CantModifyData, //an attempt was made to modify read-only data WSAPI_E_DescriptorTooSmall, //user-supplied storage for a descriptor is too small for the data being assigned to it WSAPI_E_HTTPConnectionErr, //plug-in attempted to read from a closed or non-existent HTTP stream, or some other IP-related error occurred. WSAPI_E_WrongRoleForCall, // plug-in tried to make a callback that is inappropriate for the current WSAPI_Command WSAPI_E_RequestFailed, // whatever request the plug-in was making of the server failed to complete successfully WSAPI_E_IPCMsgPending, // an attempt was made to send an IPC message while one was already in progress WSAPI_E_IPCNoMsgPending, // an attempt was made to receive IPC message results when no message was in progress WSAPI_E_Timeout, //20, requested operation took too long and timed out before being completed WSAPI_I_NoPermission, // current user doesn't have permissions for realm; other security violation WSAPI_E_ParameterIndexedOnly,//the requested parameter can only be accessed as an indexed parameter WSAPI_E_IndexedValueNotFound//the item specified by the index was not present in the requested object } WSAPI_ErrorCode; /** TCP/IP conection status codes **/ typedef enum { WSAPI_IP_Closed, //connection is closed or terminated. plug-in should stop processing WSAPI_IP_Open, //connection is open WSAPI_IP_Data, //connection is open and has unread data on it WSAPI_IP_Unknown //an unknown or unspecified error occurred } WSAPI_ConnectionStatus; /** ##Misc. W*API type definitions **/ typedef char WSAPI_IndexString [WSAPI_INDEX_SIZE]; //index selector used by WSAPI_Get and SetIndexedParameter typedef WSAPI_IndexString *WSAPI_IndexStringPtr; /********************************************************************/ //WSAPI Framework Function prototypes // You may call any of the following functions from inside your plug-in to // have WebSTAR perform the requested function. /*************************/ /** Memory Management **/ void *WSAPI_AllocateMemory (WSAPI_CommandPBPtr pb, long size); /* Allocates and returns a pointer to "size" bytes of data. Returns NULL if memory allocation fails. Do NOT use any other techniques to allocate memory within your plug-in code. All memory should be allocated using this call and disposed of using the corresponding WSAPI_FreeMemory call. */ void WSAPI_FreeMemory (WSAPI_CommandPBPtr pb, void *data); /* Deallocates a block of memory originally allocated with WSAPI_AllocateMemory. Do NOT mix and match WSAPI_AllocateOSMemory and WSAPI_FreeMemory or vice versa!!! */ void *WSAPI_AllocateOSMemory (WSAPI_CommandPBPtr pb, long size); /* Allocates and returns an O/S-specific memory accessor (e.g., a Handle under Mac O/S) to "size" bytes of data. Returns NULL if memory allocation fails. Do NOT use any other techniques to allocate memory within your plug-in code. All memory should be allocated using this call and disposed of using the corresponding WSAPI_FreeOSMemory call. */ void WSAPI_FreeOSMemory (WSAPI_CommandPBPtr pb, void *data); /* Deallocates a block of memory originally allocated with WSAPI_AllocateOSMemory. Do NOT mix and match WSAPI_AllocateMemory and WSAPI_FreeOSMemory or vice versa!!! */ /*************************/ /** Process Management **/ WSAPI_ErrorCode WSAPI_YieldTime (WSAPI_CommandPBPtr pb, long ticksToYield); /* Yields time to WebSTAR, allowing other threads, plug-ins, and processes to have access to the CPU. ticksToYield is only a suggestion to WebSTAR about how long to wait (in ticks) before resuming this thread. Control may return sooner or later than the time specified. This routine MUST be called if you are performing any processing that takes more than a few milliseconds, involves I/O of any significant amount, or would otherwise prevent normal operation of other apps in the MultiFinder environment. This call is essentially equivalent to the Thread Manager's YieldToAnyThread call. */ WSAPI_ErrorCode WSAPI_RequestIdleTime (WSAPI_CommandPBPtr pb, unsigned long ticksToSleep); /* This routine registers your plug-in with WebSTAR's idle time dispatcher. Plug-ins registered this way will have the WSAPI_Idle command sent to them at an interval approximating ticksToSleep. Plug-ins are called in the context of the idle dispatcher and will not have access to an active HTTP connection or associated data. This routine is useful for performing periodic global tasks within your plug-in. */ /*************************/ /** Networking Services **/ WSAPI_ErrorCode WSAPI_SendHTTPData (WSAPI_CommandPBPtr pb, void *data, long dataLen); /* Sends an arbitrarily large buffer of data to a HTTP client over an open HTTP connection. This implements a raw data stream to the client, allowing you to generate your own HTTP header and content, similar to what current CGI applications do now. The difference is that your data is going back in real time and you can send as much as you'd like. "data" is a pointer to a buffer containing any type of data. dataLen is the number of bytes within this buffer to transmit. No translation is performed by WebSTAR on data. You are responsible for disposing of the data pointer after this call returns, if necessary. Avoid sending many, small buffers of data with this routine if possible. NOTE: If this call ever returns a non-zero return value, you should terminate any processing and return control to WebSTAR immediately. This is an indication that the client has disconnected and WebSTAR needs to clean up the connection. */ WSAPI_ErrorCode WSAPI_ReadHTTPData (WSAPI_CommandPBPtr pb, void *data, long *dataLen); /* Reads data from the HTTP stream. Useful for reading and processing large POST args, etc., like file uploads. You must supply storage for data and pass in the maximum amount of data to be returned in the dataLen parameter. WSAPI will return up to dataLen bytes in data and will set dataLen to the actual amount of data returned. Use the WSAPI_HTTPConnectionStatus below to determine if data is pending on the HTTP connection, etc. IMPORTANT! If a pre-processor reads the HTTP object body data from a connection, that data will NOT be available to downstream plug-ins or CGIs should the pre-processor decide not to handle the URL. That means no post args for CGIs, etc. In general, it's bad form for any role other than CGI, Error, NoAccess, or Index to make this call. Specific cases excepted. Additional note, the piPostKeyword parameter can be used to repeatedly access the first 24k bytes of this data without any side effects to downstream consumers or the IP data stream. */ WSAPI_ErrorCode WSAPI_HTTPConnectionStatus (WSAPI_CommandPBPtr pb, WSAPI_ConnectionStatus *status); /* Returns the status of the HTTP connection associated with the thread that this call is made from. Obviously, this is an invalid call to make from any message handler except the RUN message. Returns the appropriate WSAPI_ConnectionStatus in the status parameter. */ //Generic Open, Close, Send, and Receive - TBS WSAPI_ErrorCode WSAPI_OpenStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream, unsigned long ip_addr, unsigned short ip_port); /* Returns a Stream pointer to an open connection to the host and port specified. ip_addr is a long integer representation of the host address, as returned from the DNS routines. If an error is returned, the stream was not successfully created. */ WSAPI_ErrorCode WSAPI_CloseStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream); /* Gracefully closes a connection opened using OpenStream. */ WSAPI_ErrorCode WSAPI_ReadStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream, void *data, long *dataLen); /* Reads up to *dataLen bytes from the specified stream. *dataLen contains the actual number of bytes read, which may be less than the number requested. */ WSAPI_ErrorCode WSAPI_WriteStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream, void *data, long dataLen); /* Writes dataLen bytes of data to the specified stream. If dataLen is too large, an error will be returned. Generally, you should never try to write more data than the maximum dump_buf_size for WebSTAR in one operation. */ WSAPI_ErrorCode WSAPI_StatusStream (WSAPI_CommandPBPtr pb, WSAPI_StreamPtr stream, WSAPI_ConnectionStatus *status, long *pending); /* Returns the status of the specified stream (open, closed, data pending) and the amount of unread data. Under OpenTransport, the pending flag will simply be positive if data exists to be read. */ WSAPI_ErrorCode WSAPI_IPNameToAddr (WSAPI_CommandPBPtr pb, char *name, unsigned long *addr); /* Converts the domain name or dotted IP address in "name" into a 4 byte IP address for use in the OpenStream call. */ /*************************/ /** Utility Functions **/ WSAPI_ErrorCode WSAPI_GetParameter (WSAPI_CommandPBPtr pb, WSAPI_ParamKeywords whichParam, WSAPI_DescPtr *descriptor); /* Use this routine to obtain descriptors that reference named WebSTAR data elements. These elements are generally equivalent to the AppleEvent parameters passed to CGIs. However, certain WebSTAR properties will also be made available via this interface. See the list of available parameters and properties above (WSAPI_ParamKeywords). You must always dispose of any descriptors returned by WSAPI_GetParameter. If the value for a parameter is undefined at the time the call is made, but the paramter is a legal one to request, WSAPI_GetParamter will return WSAPI_E_RequestFailed. If the parameter cannot be requested at the time the call is made (because of role or message conflicts), the WSAPI_E_WrongRoleForCall error will be returned. */ WSAPI_ErrorCode WSAPI_SetParameter (WSAPI_CommandPBPtr pb, WSAPI_ParamKeywords whichParam, WSAPI_DescPtr descriptor); /* Use this routine to set server parameters to the value specified in the descriptor. You need to create the descriptor first, using WSAPI_NewDescriptor. Then use WSAPI_SetDescriptor to insert values into the new descriptor before passing it to WSAPI_SetParameter. */ WSAPI_ErrorCode WSAPI_GetIndexedParameter (WSAPI_CommandPBPtr pb, WSAPI_ParamKeywords whichParam, WSAPI_IndexStringPtr index, WSAPI_DescPtr *descriptor); /* ## Use this routine to obtain descriptors that reference indexed items in a named server data element. These elements consist of values with repeating items that are specified by a unique index value for each item. Attempting to use this routine on a non-indexed parameter will simply return the value of the scalar parameter. The index selector is case-insensitive. pb may be null when appropriate. You must always dispose of any descriptors returned by WSAPI_GetIndexedParameter. If the value for a parameter is undefined at the time the call is made, but the parameter is a legal one to request, WSAPI_GetIndexedParameter will return WSAPI_E_RequestFailed. If the parameter cannot be requested at the time the call is made (because of role or message conflicts), the WSAPI_E_WrongRoleForCall error will be returned. */ WSAPI_ErrorCode WSAPI_SetIndexedParameter (WSAPI_CommandPBPtr pb, WSAPI_ParamKeywords whichParam, WSAPI_IndexStringPtr index, WSAPI_DescPtr descriptor); /* ## Use this routine to set indexed items of server elements to the value specified in the descriptor. You need to create the descriptor first, using WSAPI_NewDescriptor. Then use WSAPI_SetDescriptor to insert values into the new descriptor before passing it to WSAPI_SetIndexedParameter. Attempting to use this routine on a non-indexed parameter will simply set the value of the scalar parameter. The index selector is case-insensitive. pb may be null when appropriate. */ WSAPI_ErrorCode WSAPI_NewDescriptor (WSAPI_CommandPBPtr pb, WSAPI_DescPtr *descriptor, OSType dataType, void *data, unsigned long dataSize); /* Pass a pointer to a descriptor pointer and WSAPI will allocate it, defining the data type, size and content. If the data pointer is null when passed, a data block of dataSize will be allocated anyway and you can assign values to the descriptor later using WSAPI_SetDescriptor. If you supply data storage and pass it in the data parameter, you are responsible for deallocating the storage later. If you pass NULL, the data is allocated and deallocated by WSAPI automatically. */ WSAPI_ErrorCode WSAPI_DisposeDescriptor (WSAPI_CommandPBPtr pb, WSAPI_DescPtr *descriptor); /* Pass a pointer to a descriptor pointer that needs deallocation and WSAPI will deallocate it. */ WSAPI_ErrorCode WSAPI_GetDescriptor (WSAPI_CommandPBPtr pb, WSAPI_DescPtr descriptor, OSType *dataType, void *data, unsigned long *dataSize); /* Pass a descriptor pointer and WSAPI will return specific information about the descriptor. You must provide storage for all pointers. The data pointer must be large enough to hold the number of bytes returned in the dataSize parameter. If the data pointer is NULL, WSAPI still returns the type and size information, allowing you to then allocate an appropriately sized data container and call WSAPI_GetDescriptor again with a non-null data pointer. When called, dataSize should be initialized to the maximum size of your data buffer. On return, it will contain the actual amount of data stored in the data buffer. */ WSAPI_ErrorCode WSAPI_SetDescriptor (WSAPI_CommandPBPtr pb, WSAPI_DescPtr descriptor, void *data, unsigned long dataSize); /* Sets the data and size portions of an existing descriptor pointed to by "descriptor". Data is copied from the "data" parameter into the storage allocated inside the descriptor. If the existing data area allocated inside the descriptor is too small, the server will attempt to resize it to be large enough for dataSize bytes of data. But your plug-in should be prepared to handle a failure if the storage cannot be resized. */ WSAPI_ErrorCode WSAPI_RegisterAction (WSAPI_CommandPBPtr pb, char *actionTag, char *pluginName); /* Your plug-in must call this routine in response to the WSAPI_Register message in order to define an action that allows WebSTAR to call your plug-in. These actions are temporary and only exist while your plug-in is active. actionTag is the name of the action that will show up in Admin's transfer type pop-up. pluginName is a string that names your code fragment. Both values should be unique among all plug-ins and may be the same value. */ WSAPI_ErrorCode WSAPI_RegisterSuffix (WSAPI_CommandPBPtr pb, char *actionTag, char *suffix, OSType fileType, OSType creatorType, char *mimeType); /* Your plug-in can call this routine in response to the WSAPI_Register message in order to define suffix mappings that allows the server will use with your plug-in. These suffix mappings are temporary and only exist while your plug-in is active. actionTag is the name of the action that will be invoked when a given suffix mapping show up in Admin's transfer type pop-up. The suffix parameter is the string that the server will match (e.g., ".html") to invoke the specified action. The next two fields are machine-specific and make sense on Macs only. The last parameter is the MIME type to send with this transfer. */ WSAPI_ErrorCode WSAPI_RegisterAccessControl (WSAPI_CommandPBPtr pb); /* ## By making this call, your plug-in is registered as a handler for access control checks. There may be more than one access control handler. Your plug-in will receive a WSAPI_AccessControl message when appropriate. You should evaluate the URL and any other information necessary to determine whether or not access should be granted. Fill in the accessControl parameter block fields accordingly. If accessGranted is false, the server will refuse to allow access to that URL and if authRequired is true, it will return an appropriate HTTP response to cause the client to prompt for a username and password. Note that you are running as a "pre-" preprocessor and should not attempt to access data from the HTTP stream or otherwise manipulate information that may affect subsequent processing of the URL. Also, the first access control plug-in to refuse access terminates the access control checks, so it's not always the case that you will receive every WSAPI_AccessControl message, especially if there are other access control handlers installed before yours. */ WSAPI_ErrorCode WSAPI_RegisterFilter (WSAPI_CommandPBPtr pb); /* ## By making this call, your plug-in is registered as a filter for incoming HTTP requests. You will be sent the WSAPI_Filter message and a PB structure (WSAPI_FilterPB) that contains a pointer to the complete HTTP request and its length. This includes all header info up to and including the CRLF CRLF separator between the HTTP request and the HTTP object body (if any). You will receive this message BEFORE the server has interpreted the contents of the HTTP request. You may read any info you'd like from this request buffer, but may not modify its contents. You may also create a new buffer using WSAPI_AllocateMemory and populate it with a new HTTP request to be interpeted by the server. Since multiple filters may be installed, there is no guarantee what order you will be called in or whether or not subsequent modifications will be made to the request you generate. By setting the newRequest field to a value other than null, you inform the server that it should use your request instead of the one received from the client. You MUST create a legal HTTP 1.0 request header and include the CRLF CRLF separator at the end of the request. The server is responsible for deallocating this new request buffer when done. */ /*********************/ /* security services */ WSAPI_ErrorCode WSAPI_ValidateUser (char *name, char *passwd, char *realm); /* Using the piUserKeyword, piPasswordKeyword, and piCurrentRealm fields, you can validate whether or not a specific user should be allowed access. You may substitute your own values in place of any of the predefined parameters if desired. (e.g., pass your own realm string instead of checking only for the current realm.) Returns WSAPI_I_NoErr if the user, password, and realm are OK. Returns WSAPI_I_NoPermission if the validation fails for any reason. Note that this call will return WSAPI_E_MessageNotHandled if an external function is providing security controls for the server (e.g., a security plug-in). */ /*************************/ /** AppleEvent Services **/ // routines for registering event handlers, sending events, etc. WSAPI_ErrorCode WSAPI_SendIPCMessage (WSAPI_CommandPBPtr pb, void *msg); /* Sends an async, platform-specific interprocess communication message (e.g., AppleEvent on a Mac) that your plug-in has already constructed. For Mac O/S, pass a pointer to the AppleEvent structure you wish to send. IMPORTANT for WebSTAR Mac plug-ins!!!! For WebSTAR plug-ins, the server generates the appropriate return ID for your AppleEvent, so the value you supply to the AECreateAppleEvent call will be overwritten. If you are making this call as part of processing a message other than "Run" (i.e., that is NOT associated with a HTTP connection), you should note that your plug-in can have at most one pending event because ALL of your other message handlers run in a separate context from a HTTP connection and share a single return ID that WebSTAR uses to connect the asynch event reply to your plug-in. You are responsible for disposing any platform-specific data associated with your message after it has been sent (i.e., the event and address descriptors on Macs). */ WSAPI_ErrorCode WSAPI_WaitForIPCReply (WSAPI_CommandPBPtr pb, WSAPI_IPC_ResultPtr *msg); /* If you send an interprocess communication message (e.g., an AppleEvent under Mac O/S) and expect and asynchronous reply received by and delivered through the server to your thread of execution, you should call this routine once you expect the reply (i.e., after you've sent the IPC message). If the server receives the message reply before the timeout period defined by the server, your reply will be returned in the msg parameter. If not, msg will be null and an error code will be returned by the function. IMPORTANT for WebSTAR Mac plug-ins!!!! When the AppleEvent is returned to you, you MUST resume the AppleEvent with a call to AEResumeTheCurrentEvent. (See IM VI, 6-84) This will pass control to the handler you specify (should be a UPP to a procedure in your plug-in.) The handler must process the AE to completion. It is VERY important that your plug-in do this in a timely fashion and NOT yield time to other threads. (Well, yielding seems like a bad thing at this point because it might allow another plug-in to begin processing an event in parallel, and the AE manager is NOT reentrant and cannot process 2 events at once!) This means no callbacks until the event is handled! If msg is not null, you are responsible for disposing the msg data structure, plus any data passed to you in it if necessary. */ /*************************/ /** Logging Services **/ //TBS - routines for making log entries, processing log data, etc. WSAPI_ErrorCode WSAPI_WriteLogEntry (WSAPI_CommandPBPtr pb, char *pluginName, char *msg); /* Writes the contents of msg to the server's log file. msg should be a null terminated C string. pluginName is a C string (generally your plug-in's name) that will prefix the log entry. The combined length of pluginName and msg should be less than 510 characters. */ /*************************/ /** Status Msg Services **/ WSAPI_ErrorCode WSAPI_DisplayMessage (WSAPI_CommandPBPtr pb, char *msg); /* Writes the contents of msg on the server's status window. msg should be a null terminated C string. */ /**************************************/ /** User-supplied dispatcher routine **/ WSAPI_ErrorCode WSAPI_Dispatch (WSAPI_CommandPBPtr command); /* You must define this routine, which will be called from the WebSTAR Plug-in Framework library with a complete WSAPI_CommandPB record passed to your routine. */ #ifdef __cplusplus } #endif #if GENERATINGPOWERPC #pragma options align=reset #endif #endif 
